From d1ee8e2d4b7b83b3fbbfe39b7985bfc4b39c8264 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 14 Oct 2009 13:25:23 -0400 Subject: [PATCH] Documentation and stylistic fixups --- docs/reference/gtk/gtk-docs.sgml | 6 ++ docs/reference/gtk/gtk.types | 2 + gtk/gtkaboutdialog.c | 12 ++-- gtk/gtkcellrendererspinner.c | 109 +++++++++++++++++++------------ gtk/gtkspinner.c | 97 +++++++++++++++------------ 5 files changed, 138 insertions(+), 88 deletions(-) diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index e6e2fe401e..830f94a01e 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -161,6 +161,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. + @@ -219,6 +220,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. + @@ -491,4 +493,8 @@ that is, GUI components such as #GtkButton or #GtkTextView. Index of new symbols in 2.18 + + Index of new symbols in 2.20 + + diff --git a/docs/reference/gtk/gtk.types b/docs/reference/gtk/gtk.types index d743aa1e1a..5ed938ea35 100644 --- a/docs/reference/gtk/gtk.types +++ b/docs/reference/gtk/gtk.types @@ -29,6 +29,7 @@ gtk_cell_renderer_get_type gtk_cell_renderer_pixbuf_get_type gtk_cell_renderer_progress_get_type gtk_cell_renderer_spin_get_type +gtk_cell_renderer_spinner_get_type gtk_cell_renderer_text_get_type gtk_cell_renderer_toggle_get_type gtk_cell_view_get_type @@ -146,6 +147,7 @@ gtk_settings_get_type gtk_size_group_get_type gtk_socket_get_type gtk_spin_button_get_type +gtk_spinner_get_type gtk_statusbar_get_type gtk_status_icon_get_type gtk_style_get_type diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c index 0e5ca7e880..9cb8422a63 100644 --- a/gtk/gtkaboutdialog.c +++ b/gtk/gtkaboutdialog.c @@ -81,12 +81,13 @@ * url extending to the next space, tab or line break. * * - * Since 2.18 #GtkAboutDialog provides default website and email hooks that use - * gtk_show_uri(). - * - * If you want provide your own hooks overriding the default ones, it is important - * to do so before setting the website and email URL properties, like this: + * Since 2.18 #GtkAboutDialog provides default website and email hooks that + * use gtk_show_uri(). + * * + * If you want provide your own hooks overriding the default ones, it is + * important to do so before setting the website and email URL properties, + * like this: * * gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL); * gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url); @@ -104,7 +105,6 @@ * application, but in order to ensure proper translation of the title, * applications should set the title property explicitly when constructing * a #GtkAboutDialog, as shown in the following example: - * * * gtk_show_about_dialog (NULL, * "program-name", "ExampleCode", diff --git a/gtk/gtkcellrendererspinner.c b/gtk/gtkcellrendererspinner.c index 6501b267c8..4eb62207d6 100644 --- a/gtk/gtkcellrendererspinner.c +++ b/gtk/gtkcellrendererspinner.c @@ -34,6 +34,26 @@ #include "gtkcellrendererspinner.h" #include "gtkalias.h" + +/** + * SECTION:gtkcellrendererspinner + * @Short_description: Renders a spinning animation in a cell + * @Title: GtkCellRendererSpinner + * @See_also: #GtkSpinner, #GtkCellRendererProgress + * + * GtkCellRendererSpinner renders a spinning animation in a cell, very + * similar to #GtkSpinner. It can often be used as an alternative + * to a #GtkCellRendererProgress for displaying indefinite activity, + * instead of actual progress. + * + * To start the animation in a cell, set the #GtkCellRendererSpinner:active + * property to %TRUE and increment the #GtkCellRendererSpinner:pulse property + * at regular intervals. The usual way to set the cell renderer properties + * for each cell is to bind them to columns in your tree model using e.g. + * gtk_tree_view_column_add_attribute(). + */ + + enum { PROP_0, PROP_ACTIVE, @@ -54,28 +74,28 @@ struct _GtkCellRendererSpinnerPrivate GTK_TYPE_CELL_RENDERER_SPINNER, \ GtkCellRendererSpinnerPrivate)) -static void gtk_cell_renderer_spinner_get_property (GObject *object, - guint param_id, - GValue *value, - GParamSpec *pspec); -static void gtk_cell_renderer_spinner_set_property (GObject *object, - guint param_id, - const GValue *value, - GParamSpec *pspec); -static void gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cell, - GtkWidget *widget, - GdkRectangle *cell_area, - gint *x_offset, - gint *y_offset, - gint *width, - gint *height); -static void gtk_cell_renderer_spinner_render (GtkCellRenderer *cell, - GdkWindow *window, - GtkWidget *widget, - GdkRectangle *background_area, - GdkRectangle *cell_area, - GdkRectangle *expose_area, - guint flags); +static void gtk_cell_renderer_spinner_get_property (GObject *object, + guint param_id, + GValue *value, + GParamSpec *pspec); +static void gtk_cell_renderer_spinner_set_property (GObject *object, + guint param_id, + const GValue *value, + GParamSpec *pspec); +static void gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cell, + GtkWidget *widget, + GdkRectangle *cell_area, + gint *x_offset, + gint *y_offset, + gint *width, + gint *height); +static void gtk_cell_renderer_spinner_render (GtkCellRenderer *cell, + GdkWindow *window, + GtkWidget *widget, + GdkRectangle *background_area, + GdkRectangle *cell_area, + GdkRectangle *expose_area, + guint flags); G_DEFINE_TYPE (GtkCellRendererSpinner, gtk_cell_renderer_spinner, GTK_TYPE_CELL_RENDERER) @@ -91,7 +111,7 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass) cell_class->get_size = gtk_cell_renderer_spinner_get_size; cell_class->render = gtk_cell_renderer_spinner_render; - /* GtkCellRendererSpinner::active: + /* GtkCellRendererSpinner:active: * * Whether the spinner is active (ie. shown) in the cell * @@ -104,11 +124,15 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass) P_("Whether the spinner is active (ie. shown) in the cell"), FALSE, G_PARAM_READWRITE)); - /* GtkCellRendererSpinner::pulse: + /** + * GtkCellRendererSpinner:pulse: + * + * Pulse of the spinner. Increment this value to draw the next frame of the + * spinner animation. Usually, you would update this value in a timeout. * - * Pulse of the spinner. Increment this value to draw the next frame of the spinner animation. - * Usually, you would update this value in a timeout, every 80 milliseconds to show a full - * animation within one second. + * The #GtkSpinner widget draws one full cycle of the animation per second. + * You can learn about the number of frames used by the theme + * by looking at the #GtkSpinner:num-steps style property * * Since 2.20 */ @@ -119,7 +143,8 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass) P_("Pulse of the spinner"), 0, G_MAXUINT, 0, G_PARAM_READWRITE)); - /* GtkCellRendererSpinner::size: + /** + * GtkCellRendererSpinner:size: * * The #GtkIconSize value that specifies the size of the rendered spinner. * @@ -129,7 +154,7 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass) PROP_SIZE, g_param_spec_enum ("size", P_("Size"), - P_("The #GtkIconSize value that specifies the size of the rendered spinner"), + P_("The GtkIconSize value that specifies the size of the rendered spinner"), GTK_TYPE_ICON_SIZE, GTK_ICON_SIZE_MENU, G_PARAM_READWRITE)); @@ -164,7 +189,7 @@ gtk_cell_renderer_spinner_new (void) static void gtk_cell_renderer_spinner_update_size (GtkCellRendererSpinner *cell, - GtkWidget *widget) + GtkWidget *widget) { GtkCellRendererSpinnerPrivate *priv = cell->priv; GdkScreen *screen; @@ -238,12 +263,12 @@ gtk_cell_renderer_spinner_set_property (GObject *object, static void gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cellr, - GtkWidget *widget, - GdkRectangle *cell_area, - gint *x_offset, - gint *y_offset, - gint *width, - gint *height) + GtkWidget *widget, + GdkRectangle *cell_area, + gint *x_offset, + gint *y_offset, + gint *width, + gint *height) { GtkCellRendererSpinner *cell = GTK_CELL_RENDERER_SPINNER (cellr); GtkCellRendererSpinnerPrivate *priv = cell->priv; @@ -296,12 +321,12 @@ gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cellr, static void gtk_cell_renderer_spinner_render (GtkCellRenderer *cellr, - GdkWindow *window, - GtkWidget *widget, - GdkRectangle *background_area, - GdkRectangle *cell_area, - GdkRectangle *expose_area, - guint flags) + GdkWindow *window, + GtkWidget *widget, + GdkRectangle *background_area, + GdkRectangle *cell_area, + GdkRectangle *expose_area, + guint flags) { GtkCellRendererSpinner *cell = GTK_CELL_RENDERER_SPINNER (cellr); GtkCellRendererSpinnerPrivate *priv = cell->priv; diff --git a/gtk/gtkspinner.c b/gtk/gtkspinner.c index 63a6477265..db9307c828 100644 --- a/gtk/gtkspinner.c +++ b/gtk/gtkspinner.c @@ -38,6 +38,22 @@ #include "gtkstyle.h" #include "gtkalias.h" + +/** + * SECTION:gtkspinner + * @Short_description: Show a spinner animation + * @Title: GtkSpinner + * @See_also: #GtkCellRendererSpinner, #GtkProgressBar + * + * A GtkSpinner widget displays an icon-size spinning animation. + * It is often used as an alternative to a #GtkProgressBar for + * displaying indefinite activity, instead of actual progress. + * + * To start the animation, use gtk_spinner_start(), to stop it + * use gtk_spinner_stop(). + */ + + #define GTK_SPINNER_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_SPINNER, GtkSpinnerPrivate)) G_DEFINE_TYPE (GtkSpinner, gtk_spinner, GTK_TYPE_DRAWING_AREA); @@ -54,22 +70,26 @@ struct _GtkSpinnerPrivate guint timeout; }; -static void gtk_spinner_class_init (GtkSpinnerClass *klass); -static void gtk_spinner_init (GtkSpinner *spinner); -static void gtk_spinner_dispose (GObject *gobject); -static gboolean gtk_spinner_expose (GtkWidget *widget, GdkEventExpose *event); -static void gtk_spinner_screen_changed (GtkWidget* widget, GdkScreen* old_screen); -static void gtk_spinner_style_set (GtkWidget *widget, GtkStyle *prev_style); -static void gtk_spinner_get_property (GObject *object, - guint param_id, - GValue *value, - GParamSpec *pspec); -static void gtk_spinner_set_property (GObject *object, - guint param_id, - const GValue *value, - GParamSpec *pspec); -static AtkObject *gtk_spinner_get_accessible (GtkWidget *widget); -static GType gtk_spinner_accessible_get_type (void); +static void gtk_spinner_class_init (GtkSpinnerClass *klass); +static void gtk_spinner_init (GtkSpinner *spinner); +static void gtk_spinner_dispose (GObject *gobject); +static gboolean gtk_spinner_expose (GtkWidget *widget, + GdkEventExpose *event); +static void gtk_spinner_screen_changed (GtkWidget *widget, + GdkScreen *old_screen); +static void gtk_spinner_style_set (GtkWidget *widget, + GtkStyle *prev_style); +static void gtk_spinner_get_property (GObject *object, + guint param_id, + GValue *value, + GParamSpec *pspec); +static void gtk_spinner_set_property (GObject *object, + guint param_id, + const GValue *value, + GParamSpec *pspec); + +static AtkObject *gtk_spinner_get_accessible (GtkWidget *widget); +static GType gtk_spinner_accessible_get_type (void); static void gtk_spinner_class_init (GtkSpinnerClass *klass) @@ -91,7 +111,7 @@ gtk_spinner_class_init (GtkSpinnerClass *klass) widget_class->style_set = gtk_spinner_style_set; widget_class->get_accessible = gtk_spinner_get_accessible; - /* GtkSpinner::active: + /* GtkSpinner:active: * * Whether the spinner is active * @@ -105,17 +125,17 @@ gtk_spinner_class_init (GtkSpinnerClass *klass) FALSE, G_PARAM_READWRITE)); /** - * GtkSpinner::num-steps: + * GtkSpinner:num-steps: * - * The number of steps for the spinner to complete a full loop. The animation will - * complete a full revolution in one second. + * The number of steps for the spinner to complete a full loop. + * The animation will complete a full cycle in one second. * * Since: 2.20 */ gtk_widget_class_install_style_property (widget_class, g_param_spec_uint ("num-steps", P_("Number of steps"), - P_("The number of steps for the spinner to complete a full loop. The animation will complete a full revolution in one second."), + P_("The number of steps for the spinner to complete a full loop. The animation will complete a full cycle in one second."), 1, G_MAXUINT, 12, @@ -246,13 +266,9 @@ gtk_spinner_timeout (gpointer data) priv = GTK_SPINNER_GET_PRIVATE (data); if (priv->current + 1 >= priv->num_steps) - { - priv->current = 0; - } + priv->current = 0; else - { - priv->current++; - } + priv->current++; gtk_widget_queue_draw (GTK_WIDGET (data)); @@ -355,8 +371,8 @@ gtk_spinner_accessible_class_init (AtkObjectClass *klass) static void gtk_spinner_accessible_image_get_size (AtkImage *image, - gint *width, - gint *height) + gint *width, + gint *height) { GtkWidget *widget; @@ -465,7 +481,7 @@ gtk_spinner_get_accessible (GtkWidget *widget) } /** - * gtk_spinner_new + * gtk_spinner_new: * * Returns a new spinner widget. Not yet started. * @@ -480,9 +496,10 @@ gtk_spinner_new (void) } /** - * gtk_spinner_start + * gtk_spinner_start: + * @spinner: a #GtkSpinner * - * Starts the animation on the #GtkSpinner + * Starts the animation of the spinner. * * Since: 2.20 */ @@ -494,18 +511,19 @@ gtk_spinner_start (GtkSpinner *spinner) g_return_if_fail (GTK_IS_SPINNER (spinner)); priv = GTK_SPINNER_GET_PRIVATE (spinner); + if (priv->timeout != 0) - { - return; - } + return; + priv->timeout = gdk_threads_add_timeout (1000 / priv->num_steps, gtk_spinner_timeout, spinner); g_object_notify (G_OBJECT (spinner), "active"); } /** - * gtk_spinner_stop + * gtk_spinner_stop: + * @spinner: a #GtkSpinner * - * Stops the animation on the #GtkSpinner + * Stops the animation of the spinner. * * Since: 2.20 */ @@ -518,9 +536,8 @@ gtk_spinner_stop (GtkSpinner *spinner) priv = GTK_SPINNER_GET_PRIVATE (spinner); if (priv->timeout == 0) - { - return; - } + return; + g_source_remove (priv->timeout); priv->timeout = 0; g_object_notify (G_OBJECT (spinner), "active"); -- 2.30.2